<html>
<head><meta charset="utf-8"><title>imports only for intra-doc links · general · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/index.html">general</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/imports.20only.20for.20intra-doc.20links.html">imports only for intra-doc links</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="240355734"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/imports%20only%20for%20intra-doc%20links/near/240355734" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jonas Schievink  [he/him] <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/imports.20only.20for.20intra-doc.20links.html#240355734">(May 26 2021 at 16:53)</a>:</h4>
<p>I'm currently tempted to write this:</p>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="cp">#[allow(unused_imports)]</span><span class="w"> </span><span class="c1">// only for intra-doc links</span>
<span class="k">use</span><span class="w"> </span><span class="k">crate</span>::<span class="n">Item</span><span class="p">;</span><span class="w"></span>
</code></pre></div>
<p>...just so that I don't have to link intra-doc links to <code>crate::Item</code>. Is this a common thing to do or should I Just Not?</p>



<a name="240357588"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/imports%20only%20for%20intra-doc%20links/near/240357588" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/imports.20only.20for.20intra-doc.20links.html#240357588">(May 26 2021 at 17:05)</a>:</h4>
<p>Yeah libstd does that in a couple places too</p>



<a name="240363912"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/imports%20only%20for%20intra-doc%20links/near/240363912" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/imports.20only.20for.20intra-doc.20links.html#240363912">(May 26 2021 at 17:52)</a>:</h4>
<p>Can you use a cfg to scope it?</p>



<a name="240365701"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/imports%20only%20for%20intra-doc%20links/near/240365701" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Daniel Henry-Mantilla <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/imports.20only.20for.20intra-doc.20links.html#240365701">(May 26 2021 at 18:04)</a>:</h4>
<p>I personally use <code>#[cfg(doc)]</code> for that <span aria-label="smile" class="emoji emoji-1f642" role="img" title="smile">:smile:</span> <a href="https://play.rust-lang.org/?version=nightly&amp;mode=debug&amp;edition=2018&amp;gist=e834974737ad103edd9c9987a8a5ddb2">https://play.rust-lang.org/?version=nightly&amp;mode=debug&amp;edition=2018&amp;gist=e834974737ad103edd9c9987a8a5ddb2</a></p>



<a name="240365966"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/imports%20only%20for%20intra-doc%20links/near/240365966" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jake Goulding <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/imports.20only.20for.20intra-doc.20links.html#240365966">(May 26 2021 at 18:06)</a>:</h4>
<p>I tend to just type out the full path in the docs</p>



<a name="240366243"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/imports%20only%20for%20intra-doc%20links/near/240366243" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Daniel Henry-Mantilla <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/imports.20only.20for.20intra-doc.20links.html#240366243">(May 26 2021 at 18:08)</a>:</h4>
<p>I often do that, but for an item to which my docs refer constantly and which may not be used in the module where that happens, I am guilty of having used <code>#[cfg(doc)]</code>-gated imports <span aria-label="grinning face with smiling eyes" class="emoji emoji-1f601" role="img" title="grinning face with smiling eyes">:grinning_face_with_smiling_eyes:</span></p>



<a name="240388697"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/imports%20only%20for%20intra-doc%20links/near/240388697" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/imports.20only.20for.20intra-doc.20links.html#240388697">(May 26 2021 at 20:45)</a>:</h4>
<p><span class="user-mention silent" data-user-id="232018">Daniel Henry-Mantilla</span> <a href="#narrow/stream/122651-general/topic/imports.20only.20for.20intra-doc.20links/near/240365701">said</a>:</p>
<blockquote>
<p>I personally use <code>#[cfg(doc)]</code> for that <span aria-label="smile" class="emoji emoji-1f642" role="img" title="smile">:smile:</span> <a href="https://play.rust-lang.org/?version=nightly&amp;mode=debug&amp;edition=2018&amp;gist=e834974737ad103edd9c9987a8a5ddb2">https://play.rust-lang.org/?version=nightly&amp;mode=debug&amp;edition=2018&amp;gist=e834974737ad103edd9c9987a8a5ddb2</a></p>
</blockquote>
<p><span class="user-mention" data-user-id="232018">@Daniel Henry-Mantilla</span> that will break if the item is re-exported, cfg(doc) isn't set for dependencies</p>



<a name="240388728"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/imports%20only%20for%20intra-doc%20links/near/240388728" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/imports.20only.20for.20intra-doc.20links.html#240388728">(May 26 2021 at 20:45)</a>:</h4>
<p>and it will fail silently because it comes from another crate</p>



<a name="240392638"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/imports%20only%20for%20intra-doc%20links/near/240392638" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Daniel Henry-Mantilla <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/imports.20only.20for.20intra-doc.20links.html#240392638">(May 26 2021 at 21:14)</a>:</h4>
<p>I was talking for current-crate intra-doc links; if an item is re-exported cross-crate then it won't trigger the <code>unused_imports</code> lint to begin with, so a simple non-gated <code>pub use</code> suffices. Otherwise I am clearly missing some third possible usage <span aria-label="sweat smile" class="emoji emoji-1f605" role="img" title="sweat smile">:sweat_smile:</span></p>



<a name="240425629"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/imports%20only%20for%20intra-doc%20links/near/240425629" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Pointerbender <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/imports.20only.20for.20intra-doc.20links.html#240425629">(May 27 2021 at 06:40)</a>:</h4>
<p>There is a third way I know of:</p>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="sd">/// [Item](crate::Item) also creates a link with the text "Item", even when [crate::Item] is not imported.</span>
</code></pre></div>



<a name="240454150"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/imports%20only%20for%20intra-doc%20links/near/240454150" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Daniel Henry-Mantilla <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/imports.20only.20for.20intra-doc.20links.html#240454150">(May 27 2021 at 11:50)</a>:</h4>
<p>Sure, and within a given docstring, the path can even be factored out:</p>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="sd">/// [Item] also creates a link with the test "Item", and we can name it</span>
<span class="sd">/// several times [Item] [Item] [Item]</span>
<span class="sd">///</span>
<span class="sd">/// [Item]: crate::Item</span>
</code></pre></div>
<ul>
<li><a href="https://play.rust-lang.org/?version=nightly&amp;mode=debug&amp;edition=2018&amp;gist=dd429ab6f90febf9a023d045138114a0">Playground</a></li>
</ul>



<a name="240456701"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/imports%20only%20for%20intra-doc%20links/near/240456701" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/imports.20only.20for.20intra-doc.20links.html#240456701">(May 27 2021 at 12:10)</a>:</h4>
<p><span class="user-mention" data-user-id="232018">@Daniel Henry-Mantilla</span> the third possible usage is a public item in that module with a private import. If the item links to the import, it will break when the item is re-exported across crates if you use cfg(doc).</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>